rink documentation
(c) Ben Summers 1994

This file describes how to write a segment, and how to use the rink linker.



Writing a code segment
~~~~~~~~~~~~~~~~~~~~~~

Write your code as you would a standard C file, and compile it as usual for
an application. You don't need to set module code or anything similar. You
can write the segment in as many seperate files as you like. You can also
include AOF files written in ARM code, such as produced by objasm.

The only thing different is that the AOF files produced by the compilers are
linked together using rink rather than link, and you need to provide certain
other files although you only need create one of them.



Running rink
~~~~~~~~~~~~

rink is the rink linker. It has the command line syntax

   rink -o <segment> -l <links> -h <header description> -m <map file>
       -a <list of AOF files to link...> [-v|-vv]

The flags and switches can be in any order.

<segment> is the file name of the output segment. <links> is the file name
of the output links file. <header description> is the name of the file which
describes the segment header. It's format is described below. <map file> is
the map file created by mkptrmap for your application.

-a is followed by the list of all the AOF files you want to link together to
create the segment. You can include as many as you like, but there must be
at least one. Surprisingly.

The switch -v causes rink to output more information on what it's doing, and
-vv causes it to also output a textual table listing all the run time links
in the links file.

During the process of creating the segment rink creates the temporary file
'o.rinkXscrap' (containing the output of the inital link -aof stage). This
file is deleted after the file has been succesfully rinked.


The header description file
~~~~~~~~~~~~~~~~~~~~~~~~~~~

This file contains all the information rink needs to make the segment header.
It contains five entries, in any order. All except 'named_entries' must be
present.

id:<id name>

The id of the segment. This is the first part of the block used to check the
loaded segments. You should use a 8 character string to uniquely identify
your application.

main_version:<number>

The version of the parent application.

code_version:<number>

The version of the segment.


These three values must match those supplied in the check word to rink_load
for the rink run time system to accept the segment.


The header entries are given with entries:

entries:
<fn_name0>
<fn_name1>
...
<fn_nameN>
//

'//' terminates the list




Named functions are given with named_entries:

named_entries:
<fn_name0>
<fn_name1>
...
<fn_nameN>
//

This entry is optional. If it is not included, a named function header will
not be included in the segment.
